/*
 * File:    ClientChannel.java
 * Created: 18-Oct-2005
 * Version: $Id: //depot/bitgate/bsse/src/bitgate/util/socket/ClientChannel.java#1 $
 *
 * COPYRIGHT (C) 2005, Bitgate Software, LLC.  All Rights Reserved.
 *
 * software@bitgatesoftware.com
 */

package com.bitgate.util.socket;

import java.io.IOException;
import java.nio.ByteBuffer;
import java.nio.channels.ClosedChannelException;
import java.nio.channels.SocketChannel;

/**
 * This is a client channel interface that contains the ability to communicate with an endpoint connection.  Similar to
 * a <code>SocketChannel</code> object, but with a simpler set of functionality; however, there is still an ability to
 * get the bound <code>SocketChannel</code> object.  The main use for this interface is the ability to communicate with
 * an endpoint connected socket without having to manage the secure/nonsecure aspects of the communications.  This is done
 * in a non-blocking manner in either instance.
 *
 * @author Kenji Hollis &lt;kenji@bitgatesoftware.com&gt;
 * @version $Id: //depot/bitgate/bsse/src/bitgate/util/socket/ClientChannel.java#1 $
 */
public interface ClientChannel extends PropertiesInterface
{
    /**
     * Returns the time in milliseconds when a socket was created.  This function can be applied to protocol handlers so
     * that internal serial numbers can be attached to incoming connections, and looked up by their serials in this
     * fashion.
     *
     * @return <code>long</code> containing the number in milliseconds.
     */
    long getCreateTime();

    /**
     * Closes the connection.
     *
     * @throws IOException on any errors.
     */
    void close() throws IOException;

    /**
     * Sets the close indicator for the system to refrain from performing any further requests to a client connection.
     */
    void setIndicatorClosed();
    
    /**
     * Returns whether or not a connection is still open.
     *
     * @return <code>true</code> if the connection is open, <code>false</code> otherwise.
     */
    boolean isOpen();

    /**
     * Returns whether or not the connection is secure (SSL) or not.
     *
     * @return <code>true</code> if the connection is secure, <code>false</code> otherwise.
     */
    boolean isSecure();

    /**
     * Returns the number of bytes read into the <code>ByteBuffer</code> object.
     *
     * @param byteBuffer The object to read data into.
     * @return <code>ReadFuture</code> containing the future on read operation complete.
     * @throws IOException on any errors.
     */
    int read(ByteBuffer byteBuffer) throws IOException, ClosedChannelException;

    /**
     * Returns the number of bytes written from a <code>byte[]</code> object.
     *
     * @param data The data to send.
     * @return {@link ClientChannel} to continue chaining commands if required.
     * @throws ClosedChannelException if the socket connection is already closed.
     */
    ClientChannel write(byte[] data) throws ClosedChannelException;
    
    /**
     * Sets the write future for this object.
     * 
     * @param future The {@link WriteFuture} to set.
     */
    void setWriteFuture(WriteFuture future);
    
    /**
     * Indicates that the server has time to perform a write on this channel.  The connection should then take as many bytes
     * from its buffer as possible, and send that data.  If more data is to be written to this channel, the selector on the
     * server side will keep the connection open for write until a <code>false</code> is sent, which will then tell the server
     * to deregister the connection for write.
     * 
     * @return <code>true</code> if the buffer has more data to write, <code>false</code> otherwise.
     * @throws IOException on any errors.
     */
    boolean signalWrite() throws IOException;

    /**
     * Returns the <code>SocketChannel</code> object that is bound to the class.
     *
     * @return <code>SocketChannel</code> object.
     */
    SocketChannel getSocketChannel();
}
